home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1997 / MacHack 1997.toast / Hacks / Hacks ’96 / Booting Gallery / Booting Gallery (source) / (Libraries) / Fluent Libraries / Heaps / Heaps.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-06-22  |  3.1 KB  |  125 lines  |  [TEXT/BROW]
  1.  
  2. #ifndef _HEAPS_
  3. #define _HEAPS_
  4.  
  5. /********************************************************************
  6.  
  7.     LIBRARY:    Heaps
  8.     
  9.     PURPOSE:    To create a simple heap structure allowing
  10.                 blocks to created, deleted and iterated over.
  11.                 
  12.     AUTHORS:    Bill Hubauer (BH)
  13.     
  14.     
  15.     HISTORY:
  16.     
  17.     WHEN        WHO        WHAT
  18.     ----        ---        ----
  19.     12/27/94    BH        Created and debugged
  20.  
  21.  
  22.     
  23.  
  24. *******************************************************************/
  25.  
  26.  
  27. typedef void*    Heap;
  28.  
  29.  
  30. class SHeap {
  31.     public:
  32.  
  33.     static Heap        NewHeap(Ptr heapArea,Size theSize);
  34.     static void        DeleteHeap(Heap h);
  35.     
  36.     static Ptr        GetBlock(Heap h,Size sizeNeeded);
  37.     static OSErr    FreeBlock(Heap h,Ptr block);
  38.     
  39.     static Size        LargestFreeBlock(Heap h);
  40.     
  41.     static Ptr        FirstBlock(Heap h);
  42.     static Ptr        NextBlock(Ptr block);
  43.     
  44.     static Size        BlockSize(Ptr block);
  45.     
  46.     static void        DumpHeap(Heap h,FSSpecPtr fs);
  47.     static Size        UsedSize(Heap h);    // returns total logical size
  48.                                         // of all blocks allocated.
  49.     static Size        HeapSizeForBlock(Size sizeNeeded);        // returns the smallest heap store that will let you 
  50.                                                             // allocate a block of this size
  51. };
  52.  
  53.  
  54.  
  55. /************
  56.     DOCUMENTATION:
  57.     
  58.     This library allows you to create heaps of blocks in a fixed
  59.     memory area.
  60.     
  61.     To create a new heap use the "NewHeap" function
  62.     
  63.         Heap    NewHeap(Ptr heapArea,Size theSize);
  64.         
  65.                     heapArea:    a pointer to a preallocated hunk of memory
  66.                             of at least "theSize" size
  67.                             
  68.                     theSize:    Size of memory pointed to by heapArea
  69.                     
  70.     When you are finished with a heap you should call the DeleteHeap function.
  71.     Be aware that all blocks in the heap should be considered invalid once
  72.     this all is made.  This call does not deallocate the "heapArea" memory that
  73.     was supplied to the NewHeap call.
  74.     
  75.     
  76.     To allocate a block within the heap, call the "GetBlock" function
  77.     
  78.         Ptr    GetBlock(Heap h,Size sizeNeeded);
  79.         
  80.             h:                This is the result of the NewHeap call
  81.             sizeNeeded:        size of block you need
  82.             
  83.     If the call completes successfully you will receive a pointer to 
  84.     the block within the heap.  Use the FreeBlock function when you
  85.     are finished with the block.  If there is insuffiecient contiguous
  86.     free space in the heap, NULL will be returned.
  87.     
  88.     To deallocate a block allocated using the GetBlock call, use the FreeBlock function.
  89.         
  90.         OSErr    FreeBlock(Heap h,Ptr block);
  91.         
  92.         h:        heap that owns the block
  93.         block:    block that was allocated using the GetBlock call.
  94.         
  95.         results:
  96.             -50:    block is not valid
  97.             
  98.     To iterate over all allocated blocks, use the FirstBlock and NextBlock functions.
  99.         
  100.         Ptr        FirstBlock(Heap h);
  101.         
  102.         h:        heap in which you wish the first block.
  103.         
  104.         returns:    ptr to first block in heap or NULL if heap is empty
  105.         
  106.         
  107.         Ptr        NextBlock(Ptr block);
  108.         
  109.         block:    block for which you wish the next block.
  110.         
  111.         returns:    ptr to next block after block or NULL if block supplied is last.
  112.         
  113.         NOTE ABOUT ORDER:    Currently the order of blocks returned is undefined.  It is NOT
  114.                             in the order of allocation.
  115.                             
  116.                             
  117.     
  118.     To determine the logical size of a block, use the BlockSize function.
  119.     
  120.     To determine the largest size of a block that can be allocated using GetBlock,
  121.     use the LargetFreeBlock function.
  122. **************/
  123.  
  124.  
  125. #endif // _HEAPS_